/**
 * 会员管理API模块
 * 
 * 本文件定义了与会员管理相关的所有API接口、数据类型和请求函数。
 * 这种组织方式遵循了"按功能模块划分API"的最佳实践，使代码结构清晰，便于维护。
 */

// 导入ArcoDesign组件库中的描述列表接口类型
import type { DescData } from '@arco-design/web-vue/es/descriptions/interface'
// 导入axios用于发送HTTP请求
import axios from 'axios'
// 导入query-string库用于序列化查询参数
import qs from 'query-string'

/**
 * 分页查询参数接口
 * 
 * 定义了分页查询会员列表时需要的参数结构
 * 包含分页信息和可选的筛选条件
 */
export interface PageQuery{
  // 当前页码，从1开始
  current: number
  // 每页显示的记录数
  pageSize: number
  // 可选的筛选条件 - 会员姓名
  trueName?: string
  // 可选的筛选条件 - 手机号
  mobile?: string
  // 可选的筛选条件 - 性别(true为男，false为女)
  sex?: boolean
  // 可选的筛选条件 - 状态(true为启用，false为禁用)
  status?: boolean
  // 可选的筛选条件 - 邮箱
  email?: string
}

/**
 * 会员基本信息接口
 * 
 * 定义了会员列表中每条记录的数据结构
 */
export interface MemberRecord {
  // 会员ID，唯一标识
  userId: number,
  // 会员姓名，可能为null
  trueName: string | null
  // 手机号，必填字段
  mobile: string,
  // 性别，true表示男，false表示女
  sex: boolean,
  // 状态，true表示启用，false表示禁用
  status: boolean,
  // 邮箱，可能为null
  email: string | null
}

/**
 * 分页查询结果接口
 * 
 * 定义了分页查询返回的数据结构
 */
export interface MemberPageRes{
  // 当前页的会员列表数据
  list: MemberRecord[],
  // 总记录数，用于计算总页数
  total: number
}

/**
 * 会员详细信息接口
 * 
 * 继承自MemberRecord，包含更多的会员详细信息字段
 * 使用TypeScript的接口继承特性，避免了代码重复
 */
export interface MemberDetail extends MemberRecord {
  // 固定电话，可选
  telephone?: string | null
  // 地区，可选
  area?: string | null
  // 联系地址，可选
  contactAddr?: string | null
  // QQ号码，可选
  qq?: string | null
  // 生日，可选，字符串格式
  birthday?: string | null
  // 会员组ID，可选
  groupId?: number
  // 经验值，可选
  exp?: number
  // 积分，可选
  point?: number
  // 消息ID列表，可选
  messageIds?: string | null
  // 注册时间，可选
  time?: string | null
  // 邮政编码，可选
  zip?: string | null
  // 属性，可选
  prop?: string | null
  // 账户余额，可选
  balance?: number
  // 最后登录时间，可选
  lastLogin?: string | null
  // 自定义字段，可选
  custom?: string | null
  // 微信OpenID，可选
  openId?: string | null
  // 头像URL，可选
  avatar?: string | null
}

/**
 * 分页查询会员列表
 * 
 * @param params - 分页查询参数，包含页码、每页大小和筛选条件
 * @returns 返回一个Promise，解析为包含会员列表和总数的对象
 * 
 * 新手须知：
 * 1. axios.get<MemberPageRes>中的泛型参数指定了返回数据的类型，有助于TypeScript类型检查
 * 2. paramsSerializer用于自定义参数序列化，处理复杂参数或特殊字符
 */
export function queryMemberPage(params: PageQuery) {
  return axios.get<MemberPageRes>('/api/member/page',{
    // 传递查询参数
    params,
    // 参数序列化器，将对象转换为URL查询字符串
    // 例如：{name: 'John', age: 30} => 'name=John&age=30'
    paramsSerializer: (obj) => {
      return qs.stringify(obj)
    },
  })
}

/**
 * 获取会员详情
 * 
 * @param id - 会员ID
 * @returns 返回一个Promise，解析为会员详细信息
 * 
 * 新手须知：
 * 1. 使用模板字符串构建URL路径，更加直观
 * 2. RESTful API设计风格，通过URL路径参数传递ID
 */
export function getMemberDetail(id: number) {
  return axios.get<MemberDetail>(`/api/member/${id}`)
}

/**
 * 编辑会员信息
 * 
 * @param data - 会员详细信息对象
 * @returns 返回一个Promise，表示请求结果
 * 
 * 新手须知：
 * 1. 使用HTTP PUT方法表示更新资源
 * 2. 将整个对象作为请求体发送，符合RESTful API设计原则
 */
export function updateMember(data: MemberDetail) {
  return axios.put('/api/member', data)
}

/**
 * 启用/禁用会员
 * 
 * @param id - 会员ID
 * @returns 返回一个Promise，表示请求结果
 * 
 * 新手须知：
 * 1. 使用HTTP PUT方法表示更新资源状态
 * 2. URL路径包含操作类型(enable)和资源ID，清晰表达意图
 * 3. 这是一个幂等操作，多次调用结果相同，符合PUT方法的语义
 */
export function toggleMemberStatus(id: number) {
  return axios.put(`/api/member/enable/${id}`)
}

/**
 * 删除会员
 * 
 * @param ids - 会员ID数组，支持批量删除
 * @returns 返回一个Promise，表示请求结果
 * 
 * 新手须知：
 * 1. 使用HTTP DELETE方法表示删除资源
 * 2. 支持批量操作，传入ID数组而不是单个ID
 * 3. DELETE请求通常不带请求体，但某些后端框架支持在DELETE请求中使用请求体传递数据
 *    这里使用{data: ids}将ID数组放在请求体中，而不是查询参数中，适用于批量删除场景
 */
export function deleteMember(ids: number[]) {
  return axios.delete('/api/member', {
    data: ids
  })
}